DirectSound for QB
==================
Necros Ishtar Nodtveidt

FINAL VERSION 1.00 revision 4
This is the final revision of Version 1. The sourcecode for the slave has been cleaned up bigtime. MIDI support has been added, sample support has been removed. Why? Since Windows OSR2.1, Windows 98, and Windows Millenium all seem to support DirectSound and DOS resources simultaneously. What does this mean for you? Well, playing an MP3 through DS4QB and playing WAV sounds through your DOS program directly are not a problem. The demo that comes with DS4QB shows this in action, it has the DirectQB WAV player installed (be sure to have EMS enabled to run it). Additionally, this means that WAV playing would now be supported under true DOS, and because of the restructuring of communication, DS4QB will now actually operate under all 32-bit versions of Windows NT (Windows NT4, Windows 2000). Someone try this under Windows Whistler and find out how far you can get...

*** IMPORTANT! READ ME! ***
DIRECTSOUND FOR QUICKBASIC IS FREEWARE. IT IS DISTRIBUTED ON AN AS-IS BASIS. THE AUTHORS INVOLVED ARE NOT RESPONSIBLE FOR DAMAGES OCCURING DUE TO THE USE OF THIS SOFTWARE, ALTHOUGH IF DAMAGES OCCUR IT'S BECAUSE YOU ARE AN IDIOT WHO DOES NOT KNOW HOW TO USE A COMPUTER AND SHOULD STEP YOUR PUNK ASS BACK TO THE SIDE OF THE ROAD WITH THE REST OF THE LOSERS WHO CAN'T CODE. ADDITIONALLY, THE SOURCECODE IS COPYRIGHTED, AND BASS.DLL IS A COMMERCIAL LIBRARY. REVERSE ENGINEERING OF THE LIBRARY IS NOT ALLOWED, AND NONE OF DIRECTSOUND FOR QUICKBASIC IS PUBLIC DOMAIN. ANYONE WHO VIOLATES INTERNATIONAL COPYRIGHT LAW WILL HAVE THEIR ASS KICKED, BECAUSE MY LAWYERS CAN BEAT UP YOUR LAWYERS.
***************************
OK, enough of that...

Hello?! DirectSound for QB? What a stupid concept! Or, is it? Let's all face it: Win32 features some powerful sound applications. Wouldn't it be nice to take advantage of them for your QB projects? With very few useful sound libraries for QB, this seems a logical choice. The first time I ever saw a QB program take advantage of the Windows sound resources was Master Creating's "Shadow Of Power". Nobody outside of their group knows how it was done (many have their theories). Thanks to the Bass sound library, some assistance from Toshi Horie and QbProgger (and a few others listed below), and countless hours of slaving over interrupt 2Fh (although no longer used), now anyone can use the Bass Dynamic Link Library in their QB program.

(Note: Since this project was started, Merlin himself revealed the secret of Shadow Of Power's sound techniques, but as it is a secret, I'm not gonna tell how it was done. NEENER NEENER NEENER! =P~~~)

What does Bass.dll allow you to do?

-Play all major music module formats (MOD/S3M/XM/IT, plus MO3)
-Play MPEG-Layer 3 streams (MP3) or WAV streams
-Play CD Audio

Bass.dll does have more functionality, like EAX support and WAV samples. As most of you know, I removed the WAV sample player due to the latency issues. Additional features of Bass.dll will appear in future versions of DS4QB.

Additionally, DS4QB also allows you to do the following:
-Play MIDI music files
-Be cool and have great sound while everyone else suffers with QMIDI or BWSB...or worse

DirectSound for QB uses a file transfer scheme to communicate with a VB6-based controller. When you start your program that has the DS4QB routines in it, it starts the slave module. Without the slave module running, the sound services will not be available. Then, you send commands to the slave via the various procedures. DS4QB constantly uses two small files at the root of C:, called DS-FLAG.TMP (maximum size 1 byte) and DS-CODE.TMP (contains command to send to the slave). The flag file is used so that the DS-CODE.TMP file is not constantly being accessed (this would slow things down greatly). When all is said and done, you've got an extremely effective one-way communications system that in fact has proven FASTER than the clipboard methods due to reduced error-checking.

This document covers all the functions of DS4QB, so read up here, or view the example source that comes with this package. You will, of course, need to load QB with the default library loaded. DS4QB.BI must be '$INCLUDEd to access the routines in the library. It contains procedure declarations and all the globals that the library requires. The BI file also contains both interrupt headers and some useful constants.

DS4QB obviously requires DirectX to be installed on your computer. 99 times out of 100 this isn't a problem. If DX isn't on your system, let me schmacketh thee! err...point thee in the right direction! http://www.microsoft.com/ err somewhere on their crappy website. If you have Windows 98, DirectX 5 is built into the operating system. Officially, DS4QB requires DirectX 3 or higher (which means NT4 is supported), but Bass.dll supports special extensions of DirectX 7 (although I've not yet taken advantage of them).

DS4QB does appear to support variable-bitrate MP3s. I was just on crack before and tried to play a RIFF-based MP3 (an MP3 compressed WAV file, different than an actual MP3).

Because this requires Win32 to operate, long filenames are supported. Take advantage!

A final word before we get to the routines: although this was designed for Microsoft QuickBasic 4.5, there is absolutely no reason why this couldn't be used from ANY DOS-based language. There have already been C and DJGPP versions done by CGIJoe, and a PASCAL translation done by someone whose name I forgot...someone wanna try to make a version for the assemblers? hehehe...

ROUTINES:

SUB InitDS4QB
This starts the slave module. The slave must be on or no sound services will work (obviously).

SUB LoadModule (ModuleName AS STRING, Repeat AS INTEGER)
Loads a MOD, S3M, XM, IT, or MO3 module into memory. Set Repeat to 1 for looping. Although Bass.dll can actually load and play multiple modules at once, I limited this to one module. Multiple modules might be cool for music fading, but for now, DS4QB only supports one loaded module at a time, sorry. With alteration, it'll certainly handle more. I might implement this later.

SUB RemoveModule
Removes the module from memory.

SUB LoadStream (Filename AS STRING, Repeat AS INTEGER)
The most coveted thing in QB since the invention of the graphical library =) Loads the specified MP3 or WAV into the stream buffer. Set Repeat to 1 for autorepeat of the stream.

SUB RemoveStream
Removes the MP3 or WAV from the buffer.

SUB PlayCD (Track AS INTEGER, Repeat AS INTEGER)
If CD audio is available, this plays the CD at the specified track. Set Repeat to 1 to make it repeat. If you don't tell it to repeat, it will go on to the next track once it's done playing. There is no command to stop a CD playing, and I haven't yet tested skipping around tracks, but it SHOULD work in theory...

SUB LoadMIDI (Filename AS STRING, Repeat AS INTEGER)
Loads a MIDI file and plays it. Set Repeat to 1 for looping.

SUB RemoveMIDI
Stops the MIDI and removes it from memory.

SUB ShutdownDS4QB
Closes down the slave module and ends all playback instantly.

GLOBALS AND CONSTANTS:

False: This equals 0.
True: This is created with NOT False, so it should be -1.

WHO IS RESPONSIBLE FOR DS4QB:

-Jesus Christ: My Lord and Saviour. The reason I keep on codin'.
-Ian Luck: Wrote the Bass DLL. Excellent work dude.
-Adam Hoult: Wrote the VB API for Bass.dll. Niceness.
-NetherGoth: The BIGGEST supporter of DS4QB. Relentlessly sought out alternate communications methods as well.
-Carl Gorringe: Wrote WORKING clipboard routines. They work when mine went nuts.
-Ralf Brown: For his exhaustive efforts collecting data on PC interrupts. Damn man...I'm glad I'm not you =)
-leroy: The very first to suggest the clipboard idea, and for fixing DS4QB so it could start the slave properly.
-Logic Lord: Made some of the first suggestions for this project. Also, showed me how to heavily reduce latency.
-QbProgger: Helped out time-wise by mentioning the exact interrupt to use =)
-Toshi Horie: A massive pillar of support in using the clipboard, and pointed me to a usable program when mine went awry.
-XlatB: Let me know that I'm psychotic for using a polling clipboard =)
-Wafn: First tester of some early prototypes.
-Jorden Chamid: For hosting this product on Future Software and letting the world know it exists.
-Lord Agnathian: Suggested I control the slave's loading/unloading through the controller itself, instead of separately.
-^DaRk^: Supplied me with a DLL which ultimately became the answer to DS4QB's sample prayers (for a time).
-Merlin: Let me know the secret of his technique.
-CGIJoe: Wrote several C conversions of DS4QB and additionally added new features to them.
-fishstix: for discovering that DS4QB and DOS can work at the same time.
-Everyone on EfNet #quickbasic who liked my idea: they kinda cheered me on as the production of this went on =)
-Nekrophidius: Me! Wrote the DS4QB controller and documentations.